* initial reference section creation and configuration

* v4 docs reference plan init

* update plans

* create migration context dir

* Configure build system for major-version-reorg branch

- Temporarily disable local search plugin (will re-enable later)
- Set onBrokenLinks to 'warn' to allow build during migration
- Add /reference redirect page to handle versioned docs structure
- Create index.md files for reference directories
- Update sidebars to autogenerate from directory structure
- Document temporary changes in project brief for future re-enablement

The site now builds successfully and is ready for migration PRs.
Broken link warnings are expected as content is migrated.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* docs: migrate CLI section to v4 consolidated reference (#439)

* docs: migrate CLI section to v4 consolidated reference

Migrated Harper CLI documentation from versioned_docs to new
reference_versioned_docs/version-v4/cli/ structure following the v4
documentation consolidation plan.

Files created:
- reference_versioned_docs/version-v4/cli/overview.md
- reference_versioned_docs/version-v4/cli/commands.md
- reference_versioned_docs/version-v4/cli/operations-api-commands.md
- reference_versioned_docs/version-v4/cli/authentication.md
- migration-context/link-placeholders/cli-link-placeholders.md

Key Features:

Version Annotations - All 72 CLI operations now include "Available Since"
information with complete version coverage:
- 51 operations from v4.3.0
- 11 operations from v4.4.0 (SSH and certificate operations)
- 3 data operations from v4.4.9 (insert, update, upsert)
- 3 status operations from v4.6.0
- Individual operations from v4.7.2 and v4.7.3

Authentication Documentation - Corrected to explain Unix domain socket
authentication for local operations (automatically authenticated as
superuser). Detailed environment variable and command parameter methods
for remote operations with security best practices.

Operations API Commands - Complete operations table with all 72 operations
categorized by function, command aliases, parameter formatting guidelines,
and cross-references to related sections via tip callouts.

Process Management - Documented PID file location at <ROOTPATH>/hdb.pid,
clarified foreground/background behavior for commands, and updated dev
mode features.

Link Management - 12 internal CLI section links resolved using relative
paths. ~96 cross-section TODO links documented for future resolution in
cli-link-placeholders.md.

Content Consolidation - Merged content from v4.1 through v4.7 with inline
version annotations following Node.js documentation patterns.

Migration approach:
- Single consolidated v4 reference (no separate v4.1-v4.7 versions)
- Inline version annotations for feature availability
- TODO: prefix for cross-section links pending future migrations
- Comprehensive source attribution in HTML comments
- Learn guide links use /learn paths
- Consistent use of 'harper' command throughout

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fixup! docs: migrate CLI section to v4 consolidated reference

* fixup! docs: migrate CLI section to v4 consolidated reference

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

* GraphQL Querying Migration (#440)

* docs: migrate GraphQL Querying section to v4 consolidated reference

Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fixup! docs: migrate GraphQL Querying section to v4 consolidated reference

* fixup! fixup! docs: migrate GraphQL Querying section to v4 consolidated reference

* Update reference_versioned_docs/version-v4/graphql-querying/overview.md

Co-authored-by: Kris Zyp <kriszyp@gmail.com>

* remove coming soon sections

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Kris Zyp <kriszyp@gmail.com>

* Studio Migration (#441)

* docs: migrate Studio section to v4 consolidated reference

Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fixup! docs: migrate Studio section to v4 consolidated reference

* fixup! docs: migrate Studio section to v4 consolidated reference

* fixup! docs: migrate Studio section to v4 consolidated reference

* fixup! docs: migrate Studio section to v4 consolidated reference

* fixup! fixup! docs: migrate Studio section to v4 consolidated reference

* docs: update plans to clarify Studio vs Harper Cloud Studio distinction

* manual edits

* edit credentials/authentication info

* move additional cloud docs over per discussion

* simplify legacy cloud

* remove reference to cloud in studio docs.

* update link placeholders doc

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

* Fastify Routes Migration (#442)

* docs: migrate Fastify Routes section to v4 consolidated reference

Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fixup! docs: migrate Fastify Routes section to v4 consolidated reference

* manual tweaks

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

* format

* update map progress statusses

* update workflow to do preview deploys for new files paths

* Environment Variables Migration (#444)

* docs: migrate Environment Variables section to v4 consolidated reference

Adds the Environment Variables section focused on the built-in `loadEnv`
plugin. Harper-level env var configuration (naming conventions,
HDB_CONFIG, HARPER_DEFAULT_CONFIG, HARPER_SET_CONFIG) is intentionally
deferred to the Configuration section, with research notes captured in
the migration map.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update overview.md

Co-authored-by: Chris Barber <chris@harperdb.io>

* adjust intro

* fix titles

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Chris Barber <chris@harperdb.io>

* HTTP section migration (#446)

* docs: migrate HTTP section to v4 consolidated reference

Adds reference_versioned_docs/version-v4/http/ with four pages:
- overview.md: architecture, threading model, protocols served
- configuration.md: full http section config reference
- tls.md: top-level tls section reference (shared by HTTP and MQTT)
- api.md: server global API (server.http, Request/Response, server.ws, etc.)

Also adds migration-context/link-placeholders/http-link-placeholders.md
and updates the v4 sidebar and migration map status.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fixup! docs: migrate HTTP section to v4 consolidated reference

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Static Files Migration (#445)

* docs: migrate Static Files section to v4 consolidated reference

- Add reference_versioned_docs/version-v4/static-files/overview.md
  covering the static built-in plugin: basic usage, files/urlPath,
  v4.7 options (index, extensions, fallthrough, notFound), auto-update
  behavior, and examples including SPA client-side routing pattern
- Add Static Files category to version-v4 sidebar
- Add migration-context/link-placeholders/static-files-link-placeholders.md
- Update v4-docs-migration-map.md status to In Progress with source notes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fixup! docs: migrate Static Files section to v4 consolidated reference

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Logging Section Migration (#450)

* docs: migrate Logging section to v4 consolidated reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fixup! docs: migrate Logging section to v4 consolidated reference

* fixup! docs: migrate Logging section to v4 consolidated reference

* fixup! docs: migrate Logging section to v4 consolidated reference

* fixup! docs: migrate Logging section to v4 consolidated reference

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Analytics Section Migration (#451)

* docs: migrate Analytics section to v4 consolidated reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fixup! docs: migrate Analytics section to v4 consolidated reference

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* MQTT Section Migration (#449)

* docs: migrate MQTT section to v4 consolidated reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fixup! docs: migrate MQTT section to v4 consolidated reference

* whoops - missed a space

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Security and Users & Roles Sections Migration (#452)

* docs: migrate Security section to v4 consolidated reference

Migrates all security documentation from versioned_docs into the new
reference_versioned_docs/version-v4/security/ structure. Includes 9
pages covering authentication methods, certificate management, CORS,
SSL/HTTPS configuration, and users/roles RBAC.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: move Users & Roles to its own top-level section

Splits security/users-and-roles.md into a dedicated users-and-roles/
section with overview, configuration, and operations files. Updates
the sidebar to reflect the new top-level "Users & Roles" category.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* manual edits to security sections

* docs: add security/configuration.md and fix authentication config keys

- Add security/configuration.md covering the top-level `authentication:`
  config block (authorizeLocal, cacheTTL, enableSessions, token timeouts,
  hashFunction) with a TODO to verify the hashFunction key name
- Fix jwt-authentication.md: config was incorrectly nested under
  `operationsApi.authentication` — it is a top-level `authentication:` section
- Fix jwt-authentication.md: update broken ssl.md link to http/tls.md
- Update users-and-roles/configuration.md: replace fabricated config snippet
  with a link to security/configuration.md#hashfunction

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* finish security and users-and-roles sections

* docs: update plan to reflect users-and-roles promotion to top-level section

Notes that users-and-roles was broken out from security/ during migration,
and documents the new users-and-roles/ and security/configuration.md structure.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* pr review fixes

* switch to jsonwebtoken module reference

* remove cluster_user

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* update plan docs

* correct links

* clean up version annotations

* REST Section Migration (#457)

Adds all 5 pages of the REST reference section:
- overview.md: HTTP methods (GET/PUT/POST/PATCH/DELETE), URL structure, ETag caching, OpenAPI endpoint
- querying.md: Full URL query syntax — FIQL operators, unions, grouping, select/limit/sort functions, relationships/joins, null queries, type conversion
- headers.md: Request/response headers (ETag, If-None-Match, Content-Type, Accept, etc.)
- content-types.md: JSON, CBOR, MessagePack, CSV — with encoding recommendations
- websockets.md: WebSocket connections, custom connect() handler, MQTT-over-WS, message ordering
- server-sent-events.md: SSE connections, one-directional streaming, connect() usage

Also adds rest-link-placeholders.md and marks REST section Complete in migration map.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Database Section Migration (#458)

* docs: migrate Database section to v4 consolidated reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fixup! docs: migrate Database section to v4 consolidated reference

* fixup! fixup! docs: migrate Database section to v4 consolidated reference

* fixup! fixup! docs: migrate Database section to v4 consolidated reference

* manual review edits

* manual review edits

* remove nats section

* docs: add database/api.md for JS globals (tables, databases, transaction, createBlob)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Resources Section Migration (#459)

* docs: migrate Resources section to v4 consolidated reference

Adds overview, resource-api, global-apis, and query-optimization pages
for the Resources section of the v4 reference docs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fixup! docs: migrate Resources section to v4 consolidated reference

* fixup! docs: migrate Resources section to v4 consolidated reference

* fixup! docs: migrate Resources section to v4 consolidated reference

* fixup! docs: migrate Resources section to v4 consolidated reference

* fixup! docs: migrate Resources section to v4 consolidated reference

* fixup! docs: migrate Resources section to v4 consolidated reference

* fixup! docs: migrate Resources section to v4 consolidated reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* follow up edits from reviews

* Components Section Migration (#460)

* docs: migrate Components section to v4 consolidated reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: add JavaScript Environment page to Components section

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* manual review

* format

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Replication Section Migration (#461)

* docs: migrate Replication section to v4 consolidated reference

Adds overview.md, clustering.md, and sharding.md for the Replication section.
Updates the v4 versioned sidebar and adds a link placeholder tracker.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(replication): remove all NATS/legacy clustering content

Strips the Legacy NATS Clustering section from clustering.md, removes
NATS-era callout blockquotes from overview.md, and drops version
annotations that only make sense in a migration-history context.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* manual review

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Operations API Migration (#462)

* docs: migrate Operations API section to v4 consolidated reference

Adds overview and operations reference for the Operations API section
to the v4 consolidated reference structure.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* manual review

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Configuration Section Migration (#463)

* docs: migrate Configuration section to v4 consolidated reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* manual review

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* update plan docs and add custom functions and sql pages

* clean up progress before starting on other fixes

* Link resolution (#467)

* docs(link-resolution): resolve link placeholders in CLI section

- cli/overview.md: resolved Operations API and Configuration links
- cli/commands.md: resolved Configuration link
- cli/operations-api-commands.md: resolved all TODO links; mapped
  operations table category links to operations-api/operations.md with
  anchors (no sub-pages exist); resolved Applications → components/overview.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(link-resolution): resolve link placeholders in Fastify Routes, Studio, GraphQL Querying

- fastify-routes/overview.md: resolved Resources and REST overview links
- studio/overview.md: resolved configuration options and Operations API links
- graphql-querying/overview.md: resolved schema definition, Resources, and
  Resource Query API links

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(link-resolution): resolve link placeholders in Env Vars, Static Files, HTTP, MQTT

- environment-variables/overview.md: resolved Configuration and Components links
- static-files/overview.md: resolved all Components overview links
- http/overview.md: resolved REST Overview link
- http/configuration.md: resolved Configuration Overview link
- http/tls.md: resolved Operations API Configuration links (x2)
- http/api.md: resolved Operations API and REST Overview links
- mqtt/overview.md: resolved REST Overview link
- mqtt/configuration.md: resolved Configuration Overview link

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(link-resolution): resolve link placeholders in Logging and Analytics

- logging/configuration.md: resolved Configuration Overview link
- logging/operations.md: resolved Operations API Overview link
- analytics/overview.md: resolved Configuration Overview links (x2)
- analytics/operations.md: resolved search_by_conditions and Operations API Overview links

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(link-resolution): resolve link placeholders in Security

- security/overview.md: resolved Configuration Operations links (CORS network, TLS)
- security/mtls-authentication.md: resolved Replication clustering link
- security/certificate-verification.md: resolved Replication clustering link
- security/certificate-management.md: resolved Replication clustering link

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(link-resolution): resolve link placeholders in REST, Components, Resources, Replication

- rest/websockets.md: resolved Resource API and Resources overview links
- rest/server-sent-events.md: resolved Resources overview link
- components/overview.md: fixed malformed TODO-as-link-text for Resource API and Schema links
- components/extension-api.md: resolved server global API link
- components/plugin-api.md: resolved Resource API and server global API links
- resources/overview.md: resolved REST Overview and MQTT Overview links
- resources/query-optimization.md: resolved Schema documentation link
- replication/overview.md: resolved Certificate Verification and Certificate Management links

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(link-resolution): resolve link placeholders in Database section

- database/overview.md: resolved Resource API, Resources, Operations API, Configuration links
- database/schema.md: resolved Operations API, Resources, Configuration links
- database/api.md: resolved Resource API (x3) and Configuration links
- database/data-loader.md: resolved Extension API and Components links
- database/storage-algorithm.md: resolved Configuration links (x2)
- database/jobs.md: resolved Operations API links (x2)
- database/system-tables.md: resolved Replication clustering, Replication overview, Operations API links
- database/compaction.md: resolved Configuration link
- database/transaction.md: resolved Replication and Operations API links

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(link-resolution): resolve link placeholders in Operations API and Configuration

- operations-api/overview.md: resolved Configuration Overview link
- operations-api/operations.md: resolved SQL (→ database/sql.md) and Configuration links
- configuration/operations.md: resolved restart and restart_service operation links

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(link-resolution): delete resolved link placeholder tracker files

All link placeholders have been resolved. Removing tracker files now that
link resolution is complete.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: update MEMORY.md — Part 3 link resolution complete

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(reference): resolve broken anchors in reference/v4 docs

- security/overview: remove non-existent #network and #tls anchors from configuration/operations links
- replication/overview: remove non-existent #operations-api anchor from clustering link
- http/overview: fix server.http() anchor (#serverhttp → #serverhttplistener-options)
- logging/api: fix logging.external anchor (#logging-external → #loggingexternal)
- configuration/operations: fix restart_service anchor (#restart-service → #restart_service)
- graphql-querying/overview: fix Resource Query API link (resources/overview#query → rest/querying)
- components/applications: fix add_ssh_key anchor (#add-ssh-key → #add_ssh_key)
- components/plugin-api: add explicit {#scopehandleentry} id to handleEntry heading
- resources/overview: fix empty database/schema link

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* update memory docs

* format

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* Cross reference updates (#468)

* docs(cross-refs): update old /docs/ links in release notes to v4 reference paths

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(cross-refs): update old /docs/ links in learn guides to v4 reference paths

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(cross-refs): fix broken links and anchors from Docusaurus build

- fabric/index.md: /docs/deployments/configuration#localstudio → /reference/v4/configuration/options#localstudio
- fabric/grafana-integration.md: ../docs/developers/operations-api/analytics → /reference/v4/analytics/overview
- release-notes/4.2.0: remove broken /docs/administration/cloning link (no target page exists)
- release-notes/4.2.0: drop non-existent #adding-components-to-root anchor
- release-notes/4.5.0 + index.mdx: #blob-storage → #blob-type (correct heading anchor)
- src/pages/index.mdx: update 4 /docs/developers/* links to /reference/v4/ paths

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* update memory

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

* checkpoint before deleting old content files

* delete old docs content

* copy new content to reference/

* finish redirects

* remove paginator for reference section

* touch up sidebar styles

* copy to v5 sidebar

* add index pages

* format

* start on some new dev docs

* add version badge and update docs

* update dev docs for new VersionBadge

* fix config

* fix config to throw on broken links

* update contrib and simplify readme

* add ai generated retro for future reflection

* remove planning documents

* default to v4

* reorder rest/querying

* move sql to operations section

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Kris Zyp <kriszyp@gmail.com>
Co-authored-by: Chris Barber <chris@harperdb.io>